Creating Tools

BindAI tools expose Python application logic as executable capabilities. In V1, the simplest project tool is a Python function decorated with @tool. Tools can be used for operations such as:

Calculations
Data transformation
Business logic
API calls
Application-specific operations
External integrations

Project tools can be discovered by the BindAI runtime and used by workflow Tool nodes.

Your First Tool

The simplest BindAI tool is a decorated Python function:

from bindai_tool import tool


@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

The @tool decorator turns the function into a BindAI tool. The underlying implementation remains normal Python code.

Where to Put Tools

Project tools are normally kept in the project’s tools directory. For example:

my-project/
├── agents/
├── tools/
│   ├── echo.py
│   └── increment.py
└── workflows/

A tool module can contain:

from bindai_tool import tool


@tool
def increment(value: int) -> int:
    return value + 1

Another tool can be defined in a separate module:

from bindai_tool import tool


@tool
def echo(text: str) -> str:
    return text

Keeping tools in dedicated modules makes them easier to discover, test, and maintain.

Tool Names

The runtime uses the tool name when registering and resolving tools. For project tools, keep function names:

Short
Descriptive
Stable
Specific to the operation

For example:

@tool
def search_documents(query: str) -> list[str]:
    ...

is clearer than:

@tool
def process(data):
    ...

when the operation specifically searches documents.

Parameters

Tool parameters come from the Python function interface. For example:

@tool
def add(a: int, b: int) -> int:
    return a + b

The operation expects two inputs:

Use descriptive parameter names and type annotations.

Type Annotations

Type annotations should be used whenever possible. For example:

@tool
def multiply(a: int, b: int) -> int:
    return a * b

The signature clearly communicates:

a       -> integer
b       -> integer
return  -> integer

This makes the tool interface easier to understand and provides useful information for the BindAI tool definition.

Optional Parameters

Python default values can be used when an operation has an optional input. For example:

@tool
def search(query: str, limit: int = 5) -> list[str]:
    ...

The function has:

query  -> required
limit  -> optional, default 5

Choose defaults that are safe and useful for the operation.

Tool Descriptions

Give tools clear descriptions. A docstring is useful for communicating the purpose of a tool:

@tool
def get_customer(customer_id: int) -> dict:
    """Return customer information for a customer ID."""
    ...

A good description should make the operation clear. Prefer:

Return customer information for a customer ID.

over:

Process customer.

Descriptions should describe the actual operation rather than making broad claims about what the tool might eventually do.

Returning Values

A tool can return normal Python values. For example:

@tool
def ping() -> str:
    return "Pong"

A numeric result:

@tool
def square(value: int) -> int:
    return value * value

A list:

@tool
def colors() -> list[str]:
    return [
        "red",
        "green",
        "blue",
    ]

A dictionary:

@tool
def profile() -> dict:
    return {
        "name": "Alice",
        "active": True,
    }

Keep returned values focused on the information the surrounding application actually needs.

ToolResult

BindAI’s tool runtime uses ToolResult to represent tool execution results. A successful result can contain both the execution output and value:

ToolResult(
    success=True,
    output=result,
    value=result,
)

A failed result can contain an error:

ToolResult(
    success=False,
    output=None,
    value=None,
    error="Operation failed.",
)

The ToolResult is part of the runtime execution contract. When a tool is executed inside a workflow, the workflow runtime can preserve the result object in its variables.

Tool Failures

Tools can report operational failures through ToolResult. For example:

return ToolResult(
    success=False,
    output=None,
    value=None,
    error="Customer service unavailable.",
)

Error messages should provide useful information without exposing:

Credentials
Access tokens
Private connection information
Sensitive application state
Internal secrets

Tool Classes

BindAI also supports implementing tools as Tool objects. This is useful when the operation needs its own execution behavior or configuration. A custom tool implements the BindAI tool interface and can expose a ToolDefinition. Conceptually:

from bindai_tool import Tool

The exact implementation depends on the capability being provided. Connection-backed tools in BindAI V1 use this approach.

ToolDefinition

A BindAI ToolDefinition describes the interface exposed by a tool. It contains information such as:

Name
Description
Parameters

For example, a connection-backed Webhook tool defines a payload parameter:

ToolDefinition(
    name="webhook_example",
    description="Send a JSON payload through the configured Webhook connection.",
    parameters={
        "type": "object",
        "properties": {
            "payload": {
                "type": "object",
                "description": "JSON payload to send.",
            },
        },
        "required": ["payload"],
    },
)

The definition describes the operation without executing it.

Execution Context

Tool implementations receive an execution context. The context provides access to variables associated with the current execution. For example:

payload = context.variables.get("payload")

This is useful for tools whose inputs are supplied by the surrounding workflow. Keep normal application inputs explicit whenever possible. Use execution context when the tool genuinely needs information from the current runtime.

ToolRegistry

BindAI uses a ToolRegistry to register and resolve tools. The registry allows the runtime to find a tool by name. This is particularly important for persisted workflow definitions. A workflow stores the tool reference:

type: tool
tool: echo

At runtime, the tool registry resolves echo to the actual registered tool. Conceptually:

Workflow definition
        |
        v
    tool name
        |
        v
   ToolRegistry
        |
        v
    Tool object
        |
        v
     Execute

This keeps workflow definitions serializable without storing Python callable objects inside them.

Project Tool Discovery

The Studio runtime discovers tools from the project. For example:

my-project/
└── tools/
    ├── echo.py
    └── increment.py

The discovered tools are registered with the runtime tool registry. Studio can then expose the discovered tools through its tool API and visual workflow editor. This allows a workflow to reference a project tool by name.

Using a Tool in a Workflow

A project tool can be used by a workflow Tool node. For example:

Start
  |
  v
Tool
  |
  v
End

The workflow definition references the tool by name:

- id: tool
  type: tool
  name: Tool
  tool: echo
  output_variable: tool_output

The runtime resolves echo through the tool registry and executes it.

Tool Parameter Mapping

Workflow Tool nodes support parameter mapping. For example:

parameter_mapping:
  text: input

This means that the workflow variable:

input

is supplied to the tool parameter:

text

Conceptually:

Workflow variable
      |
      v
parameter_mapping
      |
      v
Tool parameter
      |
      v
Tool execution

This allows tools to operate on values produced by earlier workflow nodes.

Agent to Tool

Tools can be used after an Agent node. For example:

Start
  |
  v
Agent
  |
  v
Tool
  |
  v
End

The Agent node can write its result to a workflow variable:

output_variable: agent_output

The Tool node can then map that variable to one of its parameters:

parameter_mapping:
  text: agent_output

This creates a direct Agent → Tool workflow.

Multiple Tools in a Project

A project can contain multiple tools. For example:

tools/
├── echo.py
├── increment.py
├── search.py
└── customer.py

Each tool can have a focused responsibility. The runtime discovers and registers the available project tools. Workflows can then reference the appropriate tool by name.

Reusing Tools

The same project tool can be referenced by multiple workflows. For example:

tools/
└── increment.py

can be used by:

Workflow A
    |
    +---- increment

Workflow B
    |
    +---- increment

Workflow C
    |
    +---- increment

The implementation remains in one place. This makes shared application logic easier to maintain.

Connection-Backed Tools

BindAI V1 also supports tools backed by configured connections. The architecture is:

Connection
    |
    v
Connection-backed Tool
    |
    v
Workflow Tool node

The currently supported Studio connection provider is Webhook. For example, a configured connection named webh produces a connection-backed tool:

webhook_webh

The tool accepts a JSON payload and sends it through the configured Webhook connection.

Webhook Tool Example

A workflow can map a workflow variable to the Webhook tool’s payload:

- id: tool
  type: tool
  tool: webhook_webh
  output_variable: webhook_output
  parameter_mapping:
    payload: input

If input contains:

{
  "source": "bindai-api",
  "message": "Connection workflow V1 test",
  "value": 42
}

the connection-backed tool sends that payload through the configured Webhook connection. The Webhook URL is stored as connection configuration rather than embedded in the workflow definition.

Tools and Conditions

Tools can be followed by Condition nodes. For example:

Start
  |
  v
Tool
  |
  v
Condition
  |
  +---- true ----> End
  |
  +---- false ---> End

The condition evaluates workflow state and determines which path continues. The tool remains responsible only for its operation. The workflow remains responsible for control flow.

Tools and Loops

A Tool node can also participate in a workflow loop. For example:

Loop
  |
  v
Tool
  |
  v
Loop

The workflow controls repetition. The tool performs one operation each time the Tool node executes. This keeps application logic separate from workflow orchestration.

Tools and Parallel Execution

Tools can participate in parallel branches. For example:

             +--> Tool A --+
Start --> Parallel          --> Join
             +--> Tool B --+

The Parallel and Join nodes control synchronization. Each Tool node remains an independent operation.

Tools and Memory

Tools and Memory have different responsibilities. Memory stores runtime or conversation information. Tools execute operations. They can be used together in a larger application:

Agent
  |
  +---- Memory
  |
  +---- Tool

The exact behavior depends on the agent and workflow configuration.

Tools and Knowledge

Tools can also be used alongside BindAI Knowledge. Knowledge provides configured project knowledge to agent execution. Tools provide executable operations. For example:

Agent
  |
  +---- Knowledge
  |
  +---- Tool

This allows an application to combine project information with executable application logic.

API and External Services

Tools can call external services when the application requires it. For example, a project tool could wrap an HTTP API:

@tool
def lookup_status(identifier: str) -> str:
    ...

External integrations should handle their own:

Authentication
Input validation
Response validation
Error handling
Appropriate network timeouts

Do not expose credentials as ordinary tool inputs. For reusable external integrations, BindAI V1 provides the Connections layer and connection-backed tools.

File Operations

A tool can implement controlled file operations when an application requires them. For example:

from pathlib import Path

from bindai_tool import tool


@tool
def read_file(path: str) -> str:
    """Read an allowed text file."""
    return Path(path).read_text()

Applications should restrict which paths the operation is allowed to access. Do not treat a model-generated path as trusted input.

Database Operations

Database operations can also be wrapped in tools. For example:

@tool
def get_customer(customer_id: int) -> dict:
    """Return customer information for a customer ID."""
    ...

Keep database access behind explicit application operations. Avoid exposing unrestricted SQL execution directly as a model-facing tool. For state-changing operations, enforce application-level authorization and validation.

Tool Organization

As a project grows, organize tools by responsibility. For example:

tools/
├── search.py
├── customers.py
├── calculations.py
├── notifications.py
└── integrations.py

This makes the project easier to understand and keeps individual tools focused. Avoid creating a single tool that performs unrelated operations.

Read and Write Tools

It is useful to distinguish between read-oriented and state-changing operations. Read-oriented examples:

search()
get_customer()
get_status()

State-changing examples:

create_customer()
update_customer()
delete_document()
send_notification()

State-changing tools require additional care. Applications should validate inputs and enforce authorization before modifying external or persistent state.

Tool Security

Tools can execute real application operations and should therefore be treated as security boundaries. Important practices include:

Validate inputs.
Apply authorization in application code.
Protect credentials.
Do not expose secrets in tool results.
Restrict file-system access.
Restrict database access.
Keep destructive operations narrowly scoped.
Validate data before writing to external systems.

The model should not be treated as the application’s security boundary.

Testing Tools

Tools should be tested independently where possible. For example, the underlying application logic can be tested normally:

def multiply(a: int, b: int) -> int:
    return a * b


assert multiply(2, 3) == 6

Tool integration tests should additionally verify:

Tool registration
Tool discovery
Tool parameters
Successful execution
Failed execution
Tool results
Workflow parameter mapping
Connection-backed execution where applicable

Testing the operation independently from the workflow makes failures easier to diagnose.

Complete Project Example

A simple project can contain:

my-project/
├── agents/
├── tools/
│   ├── echo.py
│   └── increment.py
└── workflows/

tools/echo.py:

from bindai_tool import tool


@tool
def echo(text: str) -> str:
    """Return the supplied text."""
    return text

tools/increment.py:

from bindai_tool import tool


@tool
def increment(value: int) -> int:
    """Increment an integer by one."""
    return value + 1

A workflow can then reference the registered tool:

- id: tool
  type: tool
  name: Tool
  tool: echo
  output_variable: tool_output
  parameter_mapping:
    text: input

The runtime discovers the project tool, resolves it through the ToolRegistry, maps the workflow value to the tool parameter, and executes the operation.

Best Practices

Keep each tool focused on one responsibility.
Use descriptive function names.
Use Python type annotations.
Write concise tool descriptions.
Keep parameters explicit.
Return predictable values.
Keep tool results focused.
Handle expected operational failures.
Do not expose credentials.
Validate external inputs.
Apply authorization in application code.
Restrict destructive operations.
Test application logic independently.
Test tool registration and workflow integration.
Reuse common project tools.
Use connections for reusable external integrations.
Use workflows for multi-step orchestration.

Current V1 Scope

The verified BindAI V1 tool functionality includes:

Python project tools
The @tool decorator
Tool implementations
ToolDefinition
ToolResult
ToolRegistry
Project tool discovery
Workflow Tool nodes
Tool parameter mapping
Agent-to-Tool workflows
Connection-backed Webhook tools
Studio tool discovery

The V1 documentation does not assume an additional agent-builder tool API.

Summary

The simplest BindAI V1 tool is:

from bindai_tool import tool


@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

Project tools can be discovered and registered by the runtime. A workflow can reference the tool by name:

type: tool
tool: greet

Workflow variables can be mapped to tool parameters:

parameter_mapping:
  name: input

The runtime then resolves the tool through the ToolRegistry and executes it. For external Webhook integrations, the same workflow mechanism can use a connection-backed tool:

Connection
    |
    v
Connection-backed Tool
    |
    v
Workflow Tool node

This gives BindAI V1 a clear path from Python application logic to executable workflow capabilities while keeping tool implementations, workflow definitions, and connection configuration separate.

​Creating Tools

​Your First Tool

​Where to Put Tools

​Tool Names

​Parameters

​Type Annotations

​Optional Parameters

​Tool Descriptions

​Returning Values

​ToolResult

​Tool Failures

​Tool Classes

​ToolDefinition

​Execution Context

​ToolRegistry

​Project Tool Discovery

​Using a Tool in a Workflow

​Tool Parameter Mapping

​Agent to Tool

​Multiple Tools in a Project

​Reusing Tools

​Connection-Backed Tools

​Webhook Tool Example

​Tools and Conditions

​Tools and Loops

​Tools and Parallel Execution

​Tools and Memory

​Tools and Knowledge

​API and External Services

​File Operations

​Database Operations

​Tool Organization

​Read and Write Tools

​Tool Security

​Testing Tools

​Complete Project Example

​Best Practices

​Current V1 Scope

​Summary